---
id: workflows
title: Common Workflows
---

# Common Workflows

Quick guides for typical FVM tasks. Each workflow shows the essential commands to accomplish specific goals.

## Setting up a new project

Configure a Flutter project to use a specific SDK version.

```bash
# Navigate to project
cd myproject

# Set Flutter version
fvm use 3.19.0

# Or use latest stable
fvm use stable --pin
```

**Result:** Creates `.fvm` directory and `.fvmrc` configuration file.

## Switching between versions

Change SDK versions for different projects or testing.

```bash
# Check current version
fvm list

# Switch to different version
fvm use 3.16.0

# Force switch without validation
fvm use 3.16.0 --force
```

## Working with multiple flavors

Manage different SDK versions for development, staging, and production.

```bash
# Set development version
fvm use 3.19.0 --flavor development

# Set production version
fvm use 3.16.0 --flavor production

# Use flavor-specific version
fvm flavor development build apk
```

## Testing with different versions

Run tests across multiple Flutter SDK versions.

```bash
# Test with current project version
fvm flutter test

# Test with specific version
fvm spawn 3.19.0 test

# Test with another version
fvm spawn 3.16.0 test
```

## CI/CD integration

Set up FVM in continuous integration pipelines.

```bash
# Install FVM
dart pub global activate fvm

# Install project SDK version
fvm install

# Run Flutter commands
fvm flutter build apk --release
```

## Managing custom forks

Use company or personal Flutter forks.

```bash
# Add fork
fvm fork add company https://github.com/company/flutter.git

# Install from fork
fvm install company/stable

# Use fork version
fvm use company/3.19.0
```

## Global version setup

Configure a system-wide default Flutter version.

```bash
# Set global version
fvm global 3.19.0

# Add to PATH (one-time setup)
export PATH="$PATH:$HOME/fvm/default/bin"

# Use global version
flutter doctor
```

## Cleaning up old versions

Remove unused SDK versions to free disk space.

```bash
# List installed versions
fvm list

# Remove specific version
fvm remove 3.16.0

# Remove all versions
fvm remove --all
```

## Monorepo setup

Configure FVM for projects with multiple Flutter apps.

```bash
# Root configuration
cd monorepo
fvm use 3.19.0

# App-specific versions
cd apps/mobile
fvm use 3.16.0

# Package uses root version
cd packages/shared
# Inherits from root
```

## Offline installation

Install Flutter SDK from local cache or network share.

```bash
# Configure custom cache path
fvm config --cache-path /shared/flutter-cache

# Disable git cache for offline use
fvm config --no-use-git-cache

# Install from local cache
fvm install 3.19.0
```

## Troubleshooting

Common solutions for FVM issues.

```bash
# Check environment
fvm doctor

# Verify project setup
cd myproject
fvm doctor

# Force reinstall
fvm remove 3.19.0
fvm install 3.19.0

# Reset global config
fvm global --unlink
```

## IDE configuration

### VS Code

FVM automatically configures VS Code settings. To manually configure:

1. Run `fvm use <version>` in project
2. Restart VS Code or reload window
3. Verify SDK path in settings

### Android Studio / IntelliJ

FVM keeps a project-scoped symlink at `.fvm/flutter_sdk`. Running `fvm use <version>` updates this symlink to point to the selected Flutter SDK version.

> **Known limitation:** Android Studio and IntelliJ resolve symlinks to their absolute target path when saving settings ([flutter-intellij#6616](https://github.com/flutter/flutter-intellij/issues/6616)). This means the IDE stores the resolved path (e.g., `~/.fvm/versions/3.19.0`) rather than the symlink itself. After running `fvm use` to switch versions, you may need to re-select the SDK path in settings for the IDE to pick up the new version.

**Point the IDE at FVM**
- Open **File → Settings** (Windows/Linux) or **Android Studio → Preferences** (macOS).
- Navigate to **Languages & Frameworks → Flutter**.
- Set **Flutter SDK path** to the absolute path of `.fvm/flutter_sdk` in your project (e.g., `/path/to/project/.fvm/flutter_sdk`).
- **Tip:** Paste the path directly into the text field instead of using the file browser—this may help preserve the symlink path in some IDE versions.
- Click **Apply**. Restart the IDE if prompted.

**After switching Flutter versions**
- Run `fvm use <version>` in the project so `.fvm/flutter_sdk` points at the new cached SDK.
- Re-open **Settings → Languages & Frameworks → Flutter** and re-select the `.fvm/flutter_sdk` path so the IDE resolves to the new target.
- For Android projects: **File → Sync Project with Gradle Files** to refresh Gradle metadata. If this option isn't visible, press `Ctrl+Shift+A` (or `Cmd+Shift+A` on macOS) and search for "Sync Project with Gradle Files".
- If Dart Analysis shows stale errors, open **View → Tool Windows → Dart Analysis** and click the restart icon in the toolbar.
- Run `fvm doctor` to verify the IDE configuration is correct.

**Troubleshooting stale paths**
- Use **File → Invalidate Caches / Restart…** to clear cached SDK paths.
- Confirm the symlink exists with `ls -l .fvm/flutter_sdk`. If missing, run `fvm use` to recreate it.

**Multi-module or monorepo setups**
- Each module should run `fvm use` within its directory so `.fvm/flutter_sdk` resolves locally.
- Android Studio allows multiple Flutter SDK entries—ensure every module references its own `.fvm/flutter_sdk` rather than a shared global install.
- When switching versions in one module, repeat the Gradle/Flutter sync steps within that module’s window.

## Best practices

### Version selection

- Use specific versions for production apps
- Pin channels for active development
- Document version requirements in README

### Team collaboration

```bash
# Add to .gitignore
.fvm/flutter_sdk

# Commit these files
.fvmrc
.fvm/fvm_config.json
```

### Performance tips

- Enable git cache for faster installs
- Use `fvm install --no-setup` when you only need to cache SDKs (run `--setup` later via `fvm use`)
- Run `fvm install` in CI before build steps
